---
title: Mock Server Clients
shortTitle: Mock Server Clients
layout: page
pageOrder: 6
section: 'Mock Server'
subsection: true
sitemap:
  priority: 0.8
  changefreq: 'monthly'
  lastmod: 2018-11-16T16:00:00+01:00
---

<p>MockServer can be controlled in the following ways:</p>

<ul>
    <li><a href="#rest-api">REST API</a></li>
	<li><a href="#java-mockserver-client">Java</a></li>
	<li><a href="#javascript-mockserver-client">JavaScript</a> (both browser API & Node.js module)</li>
</ul>

<p>The following activities are supported:</p>
<ul>
    <li><a href="#button_client_create_expectation">creating expectations</a></li>
    <li><a href="#button_client_verify_reqs">verifying which requests have been received</a></li>
    <li><a href="#button_client_clear">clearing</a> or <a href="#button_client_reset">resetting</a> recorded request, expectations or logs (selectively)</li>
    <li>
        <p>Retrieving the following items:</p>
        <ul>
            <li><strong><a href="/mock_server/debugging_issues.html#retrieving_recorded_requests">recorded requests</a></strong></li>
            <li><strong><a href="/mock_server/debugging_issues.html#retrieving_active_expectations">active expectations</a></strong></li>
            <li><strong><a href="/mock_server/debugging_issues.html#retrieving_recorded_expectations">recorded expectations</a></strong></li>
            <li><strong><a href="/mock_server/debugging_issues.html#retrieving_recorded_logs">logs</a></strong></li>
        </ul>
    </li>
    <li><a href="#button_client_bind_to_additional_free_port">bind</a> additional ports for MockServer to listen on</li>
</ul>

<a name="rest-api" class="anchor" href="#rest-api">&nbsp;</a>

<h2>MockServer REST API</h2>

<p>The REST API is documented using <a href="https://app.swaggerhub.com/apis/jamesdbloom/mock-server-openapi/5.2.x">Open API specification</a></p>

<a name="java-mockserver-client" class="anchor" href="#java-mockserver-client">&nbsp;</a>

<h2>MockServer Java Client</h2>

<p>The Java client has the following version:</p>
<ul>
    <li><a href="#button_client_create_expectation"><strong>org.mockserver.client.MockServerClient</strong></a> - makes HTTP requests to a remote MockServer instance</li>
    <li><a href="#button_client_create_expectation"><strong>org.mockserver.integration.ClientAndServer</strong></a> - starts a local MockServer instance and makes HTTP requests to it</li>
</ul>

<a name="javascript-mockserver-client" class="anchor" href="#javascript-mockserver-client">&nbsp;</a>

<h2>MockServer JavaScript Client</h2>

<p>The JavaScript client has the following version:</p>

<ul>
	<li>a browser based API file <a href="https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js"><strong>mockServerClient.js</strong></a></li>
    <li>a Node.js npm module <a href="https://www.npmjs.org/package/mockserver-client"><strong>mockserver-client</strong></a><br/><a href="https://www.npmjs.org/package/mockserver-client"><img src="https://nodei.co/npm/mockserver-client.png?downloads=true&downloadRank=true&stars=true" alt="mockserver-client-node"/></a></li>
</ul>

<p>To include the browser based client in an HTML page as follows:</p>

<pre class="prettyprint lang-java code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;</code></pre>

<a name="client-code-examples" class="anchor" href="#client-code-examples">&nbsp;</a>

<button id="button_client" class="accordion title"><strong>Client Code Examples</strong></button>
<div class="panel title">
    <button id="button_client_create_expectation" class="accordion">create expectation</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
        <pre class="prettyprint lang-java code"><code class="code">new MockServerClient("localhost", 1080)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );</code></pre>
        </div>
        <button class="accordion inner">Java: ClientAndServer</button>
        <div class="panel">
        <pre class="prettyprint lang-java code"><code class="code">new ClientAndServer(1080)
    .when(
        request()
            .withMethod("GET")
            .withPath("/view/cart")
            .withCookies(
                cookie("session", "4930456C-C718-476F-971F-CB8E047AB349")
            )
            .withQueryStringParameters(
                param("cartId", "055CA455-1DF7-45BB-8535-4F83E7266092")
            )
    )
    .respond(
        response()
            .withBody("some_response_body")
    );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .mockAnyResponse({
    "httpRequest": {
      "method": "GET",
      "path": "/view/cart",
      "queryStringParameters": {
        "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
      },
      "cookies": {
        "session": "4930456C-C718-476F-971F-CB8E047AB349"
      }
    },
    "httpResponse": {
      "body": "some_response_body"
    }
  })
  .then(
    function () {
      console.log("expectation created");
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .mockAnyResponse({
      "httpRequest": {
        "method": "GET",
        "path": "/view/cart",
        "queryStringParameters": {
          "cartId": ["055CA455-1DF7-45BB-8535-4F83E7266092"]
        },
        "cookies": {
          "session": "4930456C-C718-476F-971F-CB8E047AB349"
        }
      },
      "httpResponse": {
        "body": "some_response_body"
      }
    })
    .then(
      function () {
        console.log("expectation created");
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
        <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/expectation" -d '{
  "httpRequest" : {
    "method" : "GET",
    "path" : "/view/cart",
    "queryStringParameters" : {
      "cartId" : [ "055CA455-1DF7-45BB-8535-4F83E7266092" ]
    },
    "cookies" : {
      "session" : "4930456C-C718-476F-971F-CB8E047AB349"
    }
  },
  "httpResponse" : {
    "body" : "some_response_body"
  }
}'</code></pre>
        </div>
    </div>
    <button id="button_client_verify_reqs" class="accordion">verify requests</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
        <pre class="prettyprint lang-java code"><code class="code">new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path"),
        VerificationTimes.atLeast(2)
    );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verify(
    {
      'path': '/some/path'
    }, 2, false)
  .then(
    function () {
      console.log("request found exactly 2 times");
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .verify(
      {
        'path': '/some/path'
      }, 2, false)
    .then(
      function () {
        console.log("request found exactly 2 times");
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/verify" -d '{
    "httpRequest": {
        "path": "/simple"
    },
    "times": {
        "atLeast": 2,
        "atMost": 2
    }
}'</code></pre>
        </div>
    </div>
    <button id="button_client_verify_req_sequence" class="accordion">verify request sequence</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">new MockServerClient("localhost", 1080)
    .verify(
        request()
            .withPath("/some/path/one"),
        request()
            .withPath("/some/path/two"),
        request()
            .withPath("/some/path/three")
    );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .verifySequence(
    {
      'path': '/some/path/one'
    },
    {
      'path': '/some/path/two'
    },
    {
      'path': '/some/path/three'
    }
  )
  .then(
    function () {
      console.log("request sequence found in the order specified");
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .verifySequence(
      {
        'path': '/some/path/one'
      },
      {
        'path': '/some/path/two'
      },
      {
        'path': '/some/path/three'
      }
    )
    .then(
      function () {
        console.log("request sequence found in the order specified");
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/verifySequence" -d '{
   "httpRequests":[
      {
         "path":"/some/path/one"
      },
      {
         "path":"/some/path/two"
      },
      {
         "path":"/some/path/three"
      }
   ]
}'</code></pre>
        </div>
    </div>
    <button id="button_client_retrieve_reqs" class="accordion">retrieve recorded requests</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">HttpRequest[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .retrieveRecordedRequests({
    "path": "/some/path",
    "method": "POST"
  })
  .then(
    function (recordedRequests) {
      console.log(JSON.stringify(recordedRequests));
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .retrieveRecordedRequests({
      "path": "/some/path",
      "method": "POST"
    })
    .then(
      function (recordedRequests) {
        console.log(JSON.stringify(recordedRequests));
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=REQUESTS" -d '{
    "path": "/some/path",
    "method": "POST"
}'</code></pre>
        </div>
    </div>
    <button id="button_client_retrieve_logs" class="accordion">retrieve recorded log messages</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">HttpRequest[] recordedRequests = new MockServerClient("localhost", 1080)
    .retrieveRecordedRequests(
        request()
            .withPath("/some/path")
            .withMethod("POST")
    );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .retrieveLogMessages({
    "path": "/some/path",
    "method": "POST"
  })
  .then(
    function (logMessages) {
      // logMessages is a String[]
      console.log(logMessages);
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .retrieveLogMessages({
      "path": "/some/path",
      "method": "POST"
    })
    .then(
      function (logMessages) {
        // logMessages is a String[]
        console.log(logMessages);
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/retrieve?type=LOGS" -d '{
    "path": "/some/path",
    "method": "POST"
}'</code></pre>
        </div>
    </div>
    <button id="button_client_clear" class="accordion">clear everything that matches request matcher</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/some/path")
        .withMethod("POST")
);</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .clear({
    'path': '/some/path'
  })
  .then(
    function () {
      console.log("cleared state that matches request matcher");
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .clear({
      'path': '/some/path'
    })
    .then(
      function () {
        console.log("cleared state that matches request matcher");
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/clear" -d '{
    "path": "/some/path"
}'</code></pre>
        </div>
    </div>
    <button id="button_client_clear_logs_by_req" class="accordion">clear recorded requests and logs that matches request matcher</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">new MockServerClient("localhost", 1080).clear(
    request()
        .withPath("/some/path")
        .withMethod("POST"),
    ClearType.LOG
);</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .clear({
    'path': '/some/path'
  }, 'LOG')
  .then(
    function () {
      console.log("cleared state that matches request matcher");
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .clear({
      'path': '/some/path'
    }, 'LOG')
    .then(
      function () {
        console.log("cleared state that matches request matcher");
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/clear?type=LOGS" -d '{
    "path": "/some/path"
}'</code></pre>
        </div>
    </div>
    <button id="button_client_reset" class="accordion">reset everything</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">new MockServerClient("localhost", 1080).reset();</code></pre>
        </div>
        <button class="accordion inner">JavaScript: Node.js mockserver-client</button>
        <div class="panel">
            <pre class="prettyprint lang-javascript code"><code class="code">var mockServerClient = require('mockserver-client').mockServerClient;
mockServerClient("localhost", 1080)
  .reset()
  .then(
    function () {
      console.log("reset all state");
    },
    function (error) {
      console.log(error);
    }
  );</code></pre>
        </div>
        <button class="accordion inner">JavaScript: browser mockServerClient.js</button>
        <div class="panel">
        <pre class="prettyprint lang-javascript code"><code class="code">&lt;script src=&quot;https://rawgit.com/jamesdbloom/mockserver-client-node/mockserver-5.6.1/mockServerClient.js&quot;&gt;&lt;/script&gt;
&lt;script&gt;
  mockServerClient("localhost", 1080)
    .reset()
    .then(
      function () {
        console.log("reset all state");
      },
      function (error) {
        console.log(error);
      }
    );
&lt;/script&gt;</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/reset</code></pre>
        </div>
    </div>
    <button id="button_client_bind_to_additional_free_port" class="accordion">bind to additional free port</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">List&lt;Integer&gt; boundPorts = new MockServerClient("localhost", 1080).bind(
            0
        );</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/bind -d '{
    "ports": [
        0,
        0
    ]
}'</code></pre>
        </div>
    </div>
    <button id="button_client_bind_to_additional_specified_port" class="accordion">bind to additional specified port</button>
    <div class="panel">
        <button class="accordion inner">Java: MockServerClient</button>
        <div class="panel">
            <pre class="prettyprint lang-java code"><code class="code">List&lt;Integer&gt; boundPorts = new MockServerClient("localhost", 1080).bind(
            1081, 1082
        );</code></pre>
        </div>
        <button class="accordion inner">REST API</button>
        <div class="panel">
            <pre class="prettyprint code"><code class="code">curl -v -X PUT "http://localhost:1080/mockserver/bind -d '{
    "ports": [
        1081,
        1082
    ]
}'</code></pre>
        </div>
    </div>
</div>
